
Here is a summary of the coding standards that I use when writing C.

Header files
------------

Each C source file has a header file with the same name.  This
contains all externally-visible typedefs, structs, unions, #defines
and extern procedure declarations.  Typedefs, structs, unions and
#defines that are private are in the C file.

Naming conventions
------------------

Procedures:
    lowercase letters, word breaks marked with underscores.
Variable names:
    lowercase letters, no marking of word boundaries. Uppercase
    letters occasionally used where an abbreviation is wanted,
    eg. "componentID".
Struct and union tags:
    as for variable names.
Typedefs and enum tags:
    mixed case starting with a capital letter.  Word breaks marked
    with embedded capitals.
#defines:
    uppercase letters, word breaks marked with underscores.

All extern procedure names start with the name of the C file that they
are defined in, followed by an underscore and the rest of the name.
Static procedures are not named thus, they are given whatever names I
fancy.  Procedure names are usually "big endian", what I mean is that
I would prefer "menu_object_create" to "menu_create_object".

Indentation and layout
----------------------

I use 4 spaces of indentation per level, and each curly bracket occupies
its own line.

int fact (int n)
{
    if (n > 2)
    {
        return n * fact (n - 1);
    }
    else
    {
        return n;
    }
}

(In practice I usually avoid using redundant curly brackets around
single statements like the ones around the branches of the "if"
above.)

Case labels occupy the same indentation level as the "switch" keyword:-

    switch (n)
    {
    case 1:
        blah ();
        break;
    case 3:
        blahblah ();
        break;
    }

I surround binary operators with whitespace, except for "dot" and
"arrow".  I put a space before the round brackets of a function
definition or call (some of my older code doesn't) but I don't put a
space before the square brackets of an array selection.

Structs
-------

I use a convention for naming structs that I picked up from some part
of the X sources.

typedef struct
{
    int a;
    char b[SIZE];
} SomeStrangelyNamedRec, *SomeStrangelyNamedPtr;

The "Rec" suffix is just to denote a record; I suppose I could use
"Str" instead but it it too similar to "Ptr".  The "Ptr" suffix is
just to reduce the number of asterisks in the code; I personally like
this but I know it's a bit odd.

If the struct needs to refer to itself I use:-

typedef struct _somestrangelynamedrec
{
    int a;
    char b[SIZE];
    struct _somestrangelynamedrec *next;
} SomeStrangelyNamedRec, *SomeStrangelyNamedPtr;


Comments
--------

One block comment at the start of each source file.  One block comment
at the start of each function saying what it does.  Comments within
functions are either block comments aligned with the current
indentation level, or else just hang on the right of a line of code.


  (Steve Hunt, 05-Apr-94)


Releasing new versions and the changes log
------------------------------------------

The reasons for any changes to any source file are recorded in the file
!ResEd.log; the format used can be deduced from the file itself.

From time to time, new releases of the software are made and the source
files are archived to a SrcFiler tree; details of this process are also
recorded in the log file, for example:

           common.h.resed: - version number updated to 0.27.
           !Help files updated for ResEd and the three CSEs.
           !ResEd.!Run - module version numbers updated as necessary.
           Set DEBUG = 0 in common.h.debug and DBMALLOC = 0 in
            common.h.dbmalloc - and recompile for release:
                  amu CFLAGS=-ff
                  amu install INSTDIR=$.aquarius.releases.ResEd.027
********   Version 0.27 (06-Jan-95) released on aquarius.$.release   ********
********   SrcFiler version 034 made from version 0.27 (06-Jan-95)   ********
           common.h.resed: - version number updated to 0L28.
           Set DEBUG = 1 in common.h.debug, DBMALLOC = 1 in
            common.h.dbmalloc; recompile.


How ResEd resource file header files are derived from the Toolbox headers:
--------------------------------------------------------------------------

1) #define names (eg for flags) are uppercased, as eg:

     Menu_Entry_Ticked  ->  MENU_ENTRY_TICKED

2) Tags for the components of a structure have their underlines removed,
   and, specially, id is replaced by ID:

     submenu_event  ->  submenuevent
     component_id   ->  componentID

3) Each typedef tag is replaced by <tag>Rec and *<tag>Ptr:

     MenuTemplate  ->  MenuTemplateRec, *MenuTemplatePtr

Each CSE includes a file h.resformat which includes descriptions of the
templates (as held in a resource file) for the objects which the CSE
understands.

A description of the overall resource file format is held in the header
file common.h.toolbox.

